From 7afc1291a8fe5c30564377cb3a491ea1f985b4f9 Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Thu, 25 Feb 2021 23:24:31 -0500
Subject: [PATCH] window: Convert docs

Convert link format, add an example image, add
property annotations. General cleanup.
---
 gtk/gtkwindow.c | 875 +++++++++++++++++++++++++++---------------------
 1 file changed, 486 insertions(+), 389 deletions(-)

diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index b4de2cc97c..791cab15b8 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -96,18 +96,19 @@
 #endif
 
 /**
- * SECTION:gtkwindow
- * @title: GtkWindow
- * @short_description: Toplevel which can contain other widgets
+ * GtkWindow:
+ *
+ * A `GtkWindow` is a toplevel window which can contain other widgets.
+ *
+ * ![An example GtkWindow](window.png)
  *
- * A GtkWindow is a toplevel window which can contain other widgets.
  * Windows normally have decorations that are under the control
  * of the windowing system and allow the user to manipulate the window
  * (resize it, move it, close it,...).
  *
  * # GtkWindow as GtkBuildable
  *
- * The GtkWindow implementation of the #GtkBuildable interface supports
+ * The `GtkWindow` implementation of the [iface@Gtk.Buildable] interface supports
  * setting a child as the titlebar by specifying “titlebar” as the “type”
  * attribute of a <child> element.
  *
@@ -119,7 +120,7 @@
  * ╰── <titlebar child>.titlebar [.default-decoration]
  * ]|
  *
- * GtkWindow has a main CSS node with name window and style class .background.
+ * `GtkWindow` has a main CSS node with name window and style class .background.
  *
  * Style classes that are typically used with the main CSS node are .csd (when
  * client-side decorations are in use), .solid-csd (for client-side decorations
@@ -128,7 +129,7 @@
  * style classes on the main node: .maximized, .fullscreen, .tiled (when supported,
  * also .tiled-top, .tiled-left, .tiled-right, .tiled-bottom).
  *
- * GtkWindow subclasses often add their own discriminating style classes,
+ * `GtkWindow` subclasses often add their own discriminating style classes,
  * such as .dialog, .popup or .tooltip.
  *
  * Generally, some CSS properties don't make sense on the toplevel window node,
@@ -138,12 +139,12 @@
  * resize drags. In the .csd case, the shadow area outside of the window
  * can be used to resize it.
  *
- * GtkWindow adds the .titlebar and .default-decoration style classes to the
+ * `GtkWindow` adds the .titlebar and .default-decoration style classes to the
  * widget that is added as a titlebar child.
  *
  * # Accessibility
  *
- * GtkWindow uses the %GTK_ACCESSIBLE_ROLE_WINDOW role.
+ * `GtkWindow` uses the %GTK_ACCESSIBLE_ROLE_WINDOW role.
  */
 
 #define MENU_BAR_ACCEL GDK_KEY_F10
@@ -707,6 +708,11 @@ gtk_window_class_init (GtkWindowClass *klass)
   klass->enable_debugging = gtk_window_enable_debugging;
   klass->close_request = gtk_window_close_request;
 
+  /**
+   * GtkWindow:title: (attributes org.gtk.Property.get=gtk_window_get_title org.gtk.Property.set=gtk_window_set_title)
+   *
+   * The title of the window.
+   */
   window_props[PROP_TITLE] =
       g_param_spec_string ("title",
                            P_("Window Title"),
@@ -715,11 +721,9 @@ gtk_window_class_init (GtkWindowClass *klass)
                            GTK_PARAM_READWRITE);
 
   /**
-   * GtkWindow:startup-id:
+   * GtkWindow:startup-id: (attributes org.gtk.Property.set=gtk_window_set_startup_id)
    *
-   * The :startup-id is a write-only property for setting window's
-   * startup notification identifier. See gtk_window_set_startup_id()
-   * for more details.
+   * A write-only property for setting window's startup notification identifier.
    */
   window_props[PROP_STARTUP_ID] =
       g_param_spec_string ("startup-id",
@@ -728,6 +732,11 @@ gtk_window_class_init (GtkWindowClass *klass)
                            NULL,
                            GTK_PARAM_WRITABLE);
 
+  /**
+   * GtkWindow:resizable: (attributes org.gtk.Property.get=gtk_window_get_resizable org.gtk.Property.set=gtk_window_set_resizable)
+   *
+   * If %TRUE, users can resize the window.
+   */
   window_props[PROP_RESIZABLE] =
       g_param_spec_boolean ("resizable",
                             P_("Resizable"),
@@ -735,6 +744,11 @@ gtk_window_class_init (GtkWindowClass *klass)
                             TRUE,
                             GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkWindow:modal: (attributes org.gtk.Property.get=gtk_window_get_modal org.gtk.Property.set=gtk_window_set_modal)
+   *
+   * If %TRUE, the window is modal.
+   */
   window_props[PROP_MODAL] =
       g_param_spec_boolean ("modal",
                             P_("Modal"),
@@ -742,6 +756,11 @@ gtk_window_class_init (GtkWindowClass *klass)
                             FALSE,
                             GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkWindow:default-width:
+   *
+   * The default width of the window.
+   */
   window_props[PROP_DEFAULT_WIDTH] =
       g_param_spec_int ("default-width",
                         P_("Default Width"),
@@ -750,6 +769,11 @@ gtk_window_class_init (GtkWindowClass *klass)
                         0,
                         GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkWindow:default-height:
+   *
+   * The default height of the window.
+   */
   window_props[PROP_DEFAULT_HEIGHT] =
       g_param_spec_int ("default-height",
                         P_("Default Height"),
@@ -758,6 +782,11 @@ gtk_window_class_init (GtkWindowClass *klass)
                         0,
                         GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkWindow:destroy-with-parent: (attributes org.gtk.Property.get=gtk_window_get_destroy_with_parent org.gtk.Property.set=gtk_window_set_destroy_with_parent)
+   *
+   * If this window should be destroyed when the parent is destroyed.
+   */ 
   window_props[PROP_DESTROY_WITH_PARENT] =
       g_param_spec_boolean ("destroy-with-parent",
                             P_("Destroy with Parent"),
@@ -765,14 +794,20 @@ gtk_window_class_init (GtkWindowClass *klass)
                             FALSE,
                             GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkWindow:hide-on-close: (attributes org.gtk.Property.get=gtk_window_get_hide_on_close org.gtk.Property.set=gtk_window_set_hide_on_close)
+   *
+   * If this window should be hidden when the users clicks the close button.
+   */
   window_props[PROP_HIDE_ON_CLOSE] =
       g_param_spec_boolean ("hide-on-close",
                             P_("Hide on close"),
                             P_("If this window should be hidden when the user clicks the close button"),
                             FALSE,
                             GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+
   /**
-   * GtkWindow:mnemonics-visible:
+   * GtkWindow:mnemonics-visible: (attributes org.gtk.Property.get=gtk_window_get_mnemonics_visible org.gtk.Property.set=gtk_window_set_mnemonics_visible)
    *
    * Whether mnemonics are currently visible in this window.
    *
@@ -787,7 +822,7 @@ gtk_window_class_init (GtkWindowClass *klass)
                             GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
   /**
-   * GtkWindow:focus-visible:
+   * GtkWindow:focus-visible: (attributes org.gtk.Property.get=gtk_window_get_focus_visible org.gtk.Property.set=gtk_window_set_focus_visible)
    *
    * Whether 'focus rectangles' are currently visible in this window.
    *
@@ -802,10 +837,11 @@ gtk_window_class_init (GtkWindowClass *klass)
                             GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
   /**
-   * GtkWindow:icon-name:
+   * GtkWindow:icon-name: (attributes org.gtk.Property.get=gtk_window_get_icon_name org.gtk.Property.set=gtk_window_set_icon_name)
+   *
+   * Specifies the name of the themed icon to use as the window icon.
    *
-   * The :icon-name property specifies the name of the themed icon to
-   * use as the window icon. See #GtkIconTheme for more details.
+   * See [class@Gtk.IconTheme] for more details.
    */
   window_props[PROP_ICON_NAME] =
       g_param_spec_string ("icon-name",
@@ -814,6 +850,11 @@ gtk_window_class_init (GtkWindowClass *klass)
                            NULL,
                            GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkWindow:display: (attributes org.gtk.Property.set=gtk_window_set_display)
+   *
+   * The display that will display this window.
+   */
   window_props[PROP_DISPLAY] =
       g_param_spec_object ("display",
                            P_("Display"),
@@ -821,6 +862,11 @@ gtk_window_class_init (GtkWindowClass *klass)
                            GDK_TYPE_DISPLAY,
                            GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkWindow:is-active: (attributes org.gtk.Property.get=gtk_window_is_active)
+   *
+   * Whether the toplevel is the currently active window.
+   */
   window_props[PROP_IS_ACTIVE] =
       g_param_spec_boolean ("is-active",
                             P_("Is Active"),
@@ -829,9 +875,9 @@ gtk_window_class_init (GtkWindowClass *klass)
                             GTK_PARAM_READABLE);
 
   /**
-   * GtkWindow:decorated:
+   * GtkWindow:decorated: (attributes org.gtk.Property.get=gtk_window_get_decorated org.gtk.Property.set=gtk_window_set_decorated)
    *
-   * Whether the window should be decorated by the window manager.
+   * Whether the window should have a frame (also known as *decorations*).
    */
   window_props[PROP_DECORATED] =
       g_param_spec_boolean ("decorated",
@@ -841,7 +887,7 @@ gtk_window_class_init (GtkWindowClass *klass)
                             GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
   /**
-   * GtkWindow:deletable:
+   * GtkWindow:deletable: (attributes org.gtk.Property.get=gtk_window_get_deletable org.gtk.Property.set=gtk_window_set_deletable)
    *
    * Whether the window frame should have a close button.
    */
@@ -853,10 +899,9 @@ gtk_window_class_init (GtkWindowClass *klass)
                             GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
   /**
-   * GtkWindow:transient-for:
+   * GtkWindow:transient-for: (attributes org.gtk.Property.get=gtk_window_get_transient_for org.gtk.Property.set=gtk_window_set_transient_for)
    *
-   * The transient parent of the window. See gtk_window_set_transient_for() for
-   * more details about transient windows.
+   * The transient parent of the window.
    */
   window_props[PROP_TRANSIENT_FOR] =
       g_param_spec_object ("transient-for",
@@ -866,14 +911,15 @@ gtk_window_class_init (GtkWindowClass *klass)
                            GTK_PARAM_READWRITE|G_PARAM_CONSTRUCT|G_PARAM_EXPLICIT_NOTIFY);
 
   /**
-   * GtkWindow:maximized:
+   * GtkWindow:maximized: (attributes org.gtk.Property.get=gtk_window_is_maximized)
    *
    * Whether the window is maximized.
    *
-   * Setting this property is the equivalent of calling gtk_window_maximize()
-   * and gtk_window_unmaximize(); either operation is asynchronous, which
-   * means you will need to connect to the #GObject::notify signal in order to
-   * know whether the operation was successful.
+   * Setting this property is the equivalent of calling
+   * [method@Gtk.Window.maximize] or [method@Gtk.Window.unmaximize];
+   * either operation is asynchronous, which means you will need to
+   * connect to the ::notify signal in order to know whether the
+   * operation was successful.
    */
   window_props[PROP_MAXIMIZED] =
       g_param_spec_boolean ("maximized",
@@ -883,14 +929,15 @@ gtk_window_class_init (GtkWindowClass *klass)
                             GTK_PARAM_READWRITE|G_PARAM_CONSTRUCT|G_PARAM_EXPLICIT_NOTIFY);
 
   /**
-   * GtkWindow:fullscreened:
+   * GtkWindow:fullscreened: (attributes org.gtk.Property.get=gtk_window_is_fullscreen)
    *
    * Whether the window is fullscreen.
    *
-   * Setting this property is the equivalent of calling gtk_window_fullscreen()
-   * and gtk_window_unfullscreen(); either operation is asynchronous, which
-   * means you will need to connect to the #GObject::notify signal in order to
-   * know whether the operation was successful.
+   * Setting this property is the equivalent of calling
+   * [method@Gtk.Window.fullscreen] or [method@Gtk.Window.unfullscreen];
+   * either operation is asynchronous, which means you will need to
+   * connect to the ::notify signal in order to know whether the
+   * operation was successful.
    */
   window_props[PROP_FULLSCREENED] =
       g_param_spec_boolean ("fullscreened",
@@ -900,9 +947,9 @@ gtk_window_class_init (GtkWindowClass *klass)
                             GTK_PARAM_READWRITE|G_PARAM_CONSTRUCT|G_PARAM_EXPLICIT_NOTIFY);
 
   /**
-   * GtkWindow:application:
+   * GtkWindow:application: (attributes org.gtk.Property.get=gtk_window_get_application org.gtk.Property.set=gtk_window_set_application)
    *
-   * The #GtkApplication associated with the window.
+   * The `GtkApplication` associated with the window.
    *
    * The application will be kept alive for at least as long as it
    * has any windows associated with it (see g_application_hold()
@@ -919,6 +966,11 @@ gtk_window_class_init (GtkWindowClass *klass)
                            GTK_TYPE_APPLICATION,
                            GTK_PARAM_READWRITE|G_PARAM_STATIC_STRINGS|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkWindow:default-widget: (attributes org.gtk.Property.get=gtk_window_get_default_widget org.gtk.Property.set=gtk_window_set_default_widget)
+   *
+   * The default widget.
+   */
   window_props[PROP_DEFAULT_WIDGET] =
       g_param_spec_object ("default-widget",
                            P_("Default widget"),
@@ -926,6 +978,11 @@ gtk_window_class_init (GtkWindowClass *klass)
                            GTK_TYPE_WIDGET,
                            GTK_PARAM_READWRITE|G_PARAM_STATIC_STRINGS|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkWindow:focus-widget: (attributes org.gtk.Property.get=gtk_window_get_focus org.gtk.Property.set=gtk_window_set_focus)
+   *
+   * The focus widget.
+   */
   window_props[PROP_FOCUS_WIDGET] =
       g_param_spec_object ("focus-widget",
                            P_("Focus widget"),
@@ -933,6 +990,11 @@ gtk_window_class_init (GtkWindowClass *klass)
                            GTK_TYPE_WIDGET,
                            GTK_PARAM_READWRITE|G_PARAM_STATIC_STRINGS|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkWindow:child: (attributes org.gtk.Property.get=gtk_window_get_child org.gtk.Property.set=gtk_window_set_child)
+   *
+   * The child widget.
+   */
   window_props[PROP_CHILD] =
       g_param_spec_object ("child",
                            P_("Child"),
@@ -947,10 +1009,10 @@ gtk_window_class_init (GtkWindowClass *klass)
    * GtkWindow::activate-focus:
    * @window: the window which received the signal
    *
-   * The ::activate-focus signal is a
-   * [keybinding signal][GtkSignalAction]
-   * which gets emitted when the user activates the currently
-   * focused widget of @window.
+   * Emitted when the user activates the currently focused
+   * widget of @window.
+   *
+   * This is a [keybinding signal](class.SignalAction.html).
    */
   window_signals[ACTIVATE_FOCUS] =
     g_signal_new (I_("activate-focus"),
@@ -966,10 +1028,10 @@ gtk_window_class_init (GtkWindowClass *klass)
    * GtkWindow::activate-default:
    * @window: the window which received the signal
    *
-   * The ::activate-default signal is a
-   * [keybinding signal][GtkSignalAction]
-   * which gets emitted when the user activates the default widget
+   * Emitted when the user activates the default widget
    * of @window.
+   *
+   * This is a [keybinding signal](class.SignalAction.html).
    */
   window_signals[ACTIVATE_DEFAULT] =
     g_signal_new (I_("activate-default"),
@@ -985,8 +1047,8 @@ gtk_window_class_init (GtkWindowClass *klass)
    * GtkWindow::keys-changed:
    * @window: the window which received the signal
    *
-   * The ::keys-changed signal gets emitted when the set of accelerators
-   * or mnemonics that are associated with @window changes.
+   * emitted when the set of accelerators or mnemonics that
+   * are associated with @window changes.
    */
   window_signals[KEYS_CHANGED] =
     g_signal_new (I_("keys-changed"),
@@ -1003,11 +1065,13 @@ gtk_window_class_init (GtkWindowClass *klass)
    * @window: the window on which the signal is emitted
    * @toggle: toggle the debugger
    *
-   * The ::enable-debugging signal is a [keybinding signal][GtkSignalAction]
-   * which gets emitted when the user enables or disables interactive
-   * debugging. When @toggle is %TRUE, interactive debugging is toggled
-   * on or off, when it is %FALSE, the debugger will be pointed at the
-   * widget under the pointer.
+   * Emitted when the user enables or disables interactive debugging.
+   *
+   * When @toggle is %TRUE, interactive debugging is toggled on or off,
+   * when it is %FALSE, the debugger will be pointed at the widget
+   * under the pointer.
+   *
+   * This is a [keybinding signal](class.SignalAction.html).
    *
    * The default bindings for this signal are Ctrl-Shift-I
    * and Ctrl-Shift-D.
@@ -1028,8 +1092,7 @@ gtk_window_class_init (GtkWindowClass *klass)
    * GtkWindow::close-request:
    * @window: the window on which the signal is emitted
    *
-   * The ::close-request signal is emitted when the user clicks on the close
-   * button of the window.
+   * Emitted when the user clicks on the close button of the window.
    *
    * Return: %TRUE to stop other handlers from being invoked for the signal
    */
@@ -1112,8 +1175,8 @@ gtk_window_class_init (GtkWindowClass *klass)
 }
 
 /**
- * gtk_window_is_maximized:
- * @window: a #GtkWindow
+ * gtk_window_is_maximized: (attributes org.gtk.Method.get_property=maximized)
+ * @window: a `GtkWindow`
  *
  * Retrieves the current maximized state of @window.
  *
@@ -1121,7 +1184,7 @@ gtk_window_class_init (GtkWindowClass *klass)
  * manager and happens asynchronously to an application request, you
  * shouldn’t assume the return value of this function changing
  * immediately (or at all), as an effect of calling
- * gtk_window_maximize() or gtk_window_unmaximize().
+ * [method@Gtk.Window.maximize] or [method@Gtk.Window.unmaximize].
  *
  * If the window isn't yet mapped, the value returned will whether the
  * initial requested state is maximized.
@@ -1139,8 +1202,8 @@ gtk_window_is_maximized (GtkWindow *window)
 }
 
 /**
- * gtk_window_is_fullscreen:
- * @window: a #GtkWindow
+ * gtk_window_is_fullscreen: (attributes org.gtk.Property.get=fullscreened)
+ * @window: a `GtkWindow`
  *
  * Retrieves the current fullscreen state of @window.
  *
@@ -1148,7 +1211,7 @@ gtk_window_is_maximized (GtkWindow *window)
  * manager and happens asynchronously to an application request, you
  * shouldn’t assume the return value of this function changing
  * immediately (or at all), as an effect of calling
- * gtk_window_fullscreen() or gtk_window_unfullscreen().
+ * [method@Gtk.Window.fullscreen] or [method@Gtk.Window.unfullscreen].
  *
  * If the window isn't yet mapped, the value returned will whether the
  * initial requested state is fullscreen.
@@ -1178,10 +1241,12 @@ _gtk_window_toggle_maximized (GtkWindow *window)
 
 /**
  * gtk_window_close:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
+ *
+ * Requests that the window is closed.
  *
- * Requests that the window is closed, similar to what happens
- * when a window manager close button is clicked.
+ * This is similar to what happens when a window manager
+ * close button is clicked.
  *
  * This function can be used with close buttons in custom
  * titlebars.
@@ -2015,23 +2080,22 @@ gtk_window_native_interface_init (GtkNativeInterface *iface)
 
 /**
  * gtk_window_new:
- * 
- * Creates a new #GtkWindow, which is a toplevel window that can
- * contain other widgets.
+ *
+ * Creates a new `GtkWindow`.
  *
  * To get an undecorated window (no window borders), use
- * gtk_window_set_decorated().
+ * [method@Gtk.Window.set_decorated].
  *
- * All top-level windows created by gtk_window_new() are stored in
- * an internal top-level window list.  This list can be obtained from
- * gtk_window_list_toplevels().  Due to Gtk+ keeping a reference to
- * the window internally, gtk_window_new() does not return a reference
- * to the caller.
+ * All top-level windows created by gtk_window_new() are stored
+ * in an internal top-level window list. This list can be obtained
+ * from [func@Gtk.Window.list_toplevels]. Due to GTK keeping a
+ * reference to the window internally, gtk_window_new() does not
+ * return a reference to the caller.
  *
- * To delete a #GtkWindow, call gtk_window_destroy().
- * 
- * Returns: a new #GtkWindow.
- **/
+ * To delete a `GtkWindow`, call [method@Gtk.Window.destroy].
+ *
+ * Returns: a new `GtkWindow`.
+ */
 GtkWidget*
 gtk_window_new (void)
 {
@@ -2039,22 +2103,21 @@ gtk_window_new (void)
 }
 
 /**
- * gtk_window_set_title:
- * @window: a #GtkWindow
+ * gtk_window_set_title: (attributes org.gtk.Method.set_property=title)
+ * @window: a `GtkWindow`
  * @title: (nullable): title of the window
- * 
- * Sets the title of the #GtkWindow. The title of a window will be
- * displayed in its title bar; on the X Window System, the title bar
- * is rendered by the [window manager][gtk-X11-arch],
- * so exactly how the title appears to users may vary
- * according to a user’s exact configuration. The title should help a
- * user distinguish this window from other windows they may have
- * open. A good title might include the application name and current
- * document filename, for example.
- * document filename, for example.
-
+ *
+ * Sets the title of the `GtkWindow`.
+ *
+ * The title of a window will be displayed in its title bar; on the
+ * X Window System, the title bar is rendered by the window manager
+ * so exactly how the title appears to users may vary according to a
+ * user’s exact configuration. The title should help a user distinguish
+ * this window from other windows they may have open. A good title might
+ * include the application name and current document filename, for example.
+ *
  * Passing %NULL does the same as setting the title to an empty string.
- **/
+ */
 void
 gtk_window_set_title (GtkWindow  *window,
                       const char *title)
@@ -2079,15 +2142,15 @@ gtk_window_set_title (GtkWindow  *window,
 }
 
 /**
- * gtk_window_get_title:
- * @window: a #GtkWindow
+ * gtk_window_get_title: (attributes org.gtk.Method.get_property=title)
+ * @window: a `GtkWindow`
  *
- * Retrieves the title of the window. See gtk_window_set_title().
+ * Retrieves the title of the window.
  *
  * Returns: (nullable): the title of the window, or %NULL if none has
- * been set explicitly. The returned string is owned by the widget
- * and must not be modified or freed.
- **/
+ *   been set explicitly. The returned string is owned by the widget
+ *   and must not be modified or freed.
+ */
 const char *
 gtk_window_get_title (GtkWindow *window)
 {
@@ -2099,21 +2162,25 @@ gtk_window_get_title (GtkWindow *window)
 }
 
 /**
- * gtk_window_set_startup_id:
- * @window: a #GtkWindow
+ * gtk_window_set_startup_id: (attributes org.gtk.Method.set_property=startup-id)
+ * @window: a `GtkWindow`
  * @startup_id: a string with startup-notification identifier
  *
- * Startup notification identifiers are used by desktop environment to 
- * track application startup, to provide user feedback and other 
+ * Sets the startup notification ID.
+ *
+ * Startup notification identifiers are used by desktop environment
+ * to track application startup, to provide user feedback and other
  * features. This function changes the corresponding property on the
- * underlying GdkSurface. Normally, startup identifier is managed 
- * automatically and you should only use this function in special cases
- * like transferring focus from other processes. You should use this
- * function before calling gtk_window_present() or any equivalent
- * function generating a window map event.
+ * underlying `GdkSurface`.
+ *
+ * Normally, startup identifier is managed automatically and you should
+ * only use this function in special cases like transferring focus from
+ * other processes. You should use this function before calling
+ * [method@Gtk.Window.present] or any equivalent function generating
+ * a window map event.
  *
  * This function is only useful on X11, not with other GTK targets.
- **/
+ */
 void
 gtk_window_set_startup_id (GtkWindow   *window,
                            const char *startup_id)
@@ -2156,14 +2223,15 @@ gtk_window_set_startup_id (GtkWindow   *window,
 }
 
 /**
- * gtk_window_set_default_widget:
- * @window: a #GtkWindow
+ * gtk_window_set_default_widget: (attributes org.gtk.Property.set=default-widget)
+ * @window: a `GtkWindow`
  * @default_widget: (allow-none): widget to be the default, or %NULL
  *     to unset the default widget for the toplevel
  *
- * The default widget is the widget that’s activated when the user
- * presses Enter in a dialog (for example). This function sets or
- * unsets the default widget for a #GtkWindow.
+ * Sets the default widget.
+ *
+ * The default widget is the widget that is activated when the user
+ * presses Enter in a dialog (for example).
  */
 void
 gtk_window_set_default_widget (GtkWindow *window,
@@ -2216,16 +2284,14 @@ gtk_window_set_default_widget (GtkWindow *window,
 }
 
 /**
- * gtk_window_get_default_widget:
- * @window: a #GtkWindow
+ * gtk_window_get_default_widget: (attributes org.gtk.Property.get=default-widget)
+ * @window: a `GtkWindow`
  *
  * Returns the default widget for @window.
  *
- * See gtk_window_set_default_widget() for more details.
- *
  * Returns: (nullable) (transfer none): the default widget, or %NULL
- * if there is none.
- **/
+ *   if there is none.
+ */
 GtkWidget *
 gtk_window_get_default_widget (GtkWindow *window)
 {
@@ -2266,18 +2332,19 @@ _gtk_window_notify_keys_changed (GtkWindow *window)
 }
 
 /**
- * gtk_window_get_focus:
- * @window: a #GtkWindow
- * 
+ * gtk_window_get_focus: (attributes org.gtk.Property.get=focus-widget)
+ * @window: a `GtkWindow`
+ *
  * Retrieves the current focused widget within the window.
+ *
  * Note that this is the widget that would have the focus
  * if the toplevel window focused; if the toplevel window
- * is not focused then  `gtk_widget_has_focus (widget)` will
+ * is not focused then `gtk_widget_has_focus (widget)` will
  * not be %TRUE for the widget.
  *
  * Returns: (nullable) (transfer none): the currently focused widget,
- * or %NULL if there is none.
- **/
+ *   or %NULL if there is none.
+ */
 GtkWidget *
 gtk_window_get_focus (GtkWindow *window)
 {
@@ -2301,17 +2368,18 @@ gtk_window_real_activate_default (GtkWindow *window)
 }
 
 /**
- * gtk_window_set_modal:
- * @window: a #GtkWindow
+ * gtk_window_set_modal: (attributes org.gtk.Method.set_property=modal)
+ * @window: a `GtkWindow`
  * @modal: whether the window is modal
  *
- * Sets a window modal or non-modal. Modal windows prevent interaction
- * with other windows in the same application. To keep modal dialogs
- * on top of main application windows, use
- * gtk_window_set_transient_for() to make the dialog transient for the
- * parent; most [window managers][gtk-X11-arch]
- * will then disallow lowering the dialog below the parent.
- **/
+ * Sets a window modal or non-modal.
+ *
+ * Modal windows prevent interaction with other windows in the same
+ * application. To keep modal dialogs on top of main application windows,
+ * use [method@Gtk.Window.set_transient_for] to make the dialog transient
+ * for the parent; most window managers will then disallow lowering the
+ * dialog below the parent.
+ */
 void
 gtk_window_set_modal (GtkWindow *window,
                       gboolean   modal)
@@ -2349,14 +2417,14 @@ gtk_window_set_modal (GtkWindow *window,
 }
 
 /**
- * gtk_window_get_modal:
- * @window: a #GtkWindow
- * 
- * Returns whether the window is modal. See gtk_window_set_modal().
+ * gtk_window_get_modal: (attributes org.gtk.Method.get_property=modal)
+ * @window: a `GtkWindow`
+ *
+ * Returns whether the window is modal.
  *
  * Returns: %TRUE if the window is set to be modal and
- *               establishes a grab when shown
- **/
+ *   establishes a grab when shown
+ */
 gboolean
 gtk_window_get_modal (GtkWindow *window)
 {
@@ -2390,16 +2458,18 @@ gtk_window_get_toplevels (void)
 
 /**
  * gtk_window_list_toplevels:
- * 
- * Returns a list of all existing toplevel windows. The widgets
- * in the list are not individually referenced. If you want
- * to iterate through the list and perform actions involving
- * callbacks that might destroy the widgets, you must call
- * `g_list_foreach (result, (GFunc)g_object_ref, NULL)` first, and
- * then unref all the widgets afterwards.
- *
- * Returns: (element-type GtkWidget) (transfer container): list of toplevel widgets
- **/
+ *
+ * Returns a list of all existing toplevel windows.
+ *
+ * The widgets in the list are not individually referenced.
+ * If you want to iterate through the list and perform actions
+ * involving callbacks that might destroy the widgets, you must
+ * call `g_list_foreach (result, (GFunc)g_object_ref, NULL)` first,
+ * and then unref all the widgets afterwards.
+ *
+ * Returns: (element-type GtkWidget) (transfer container): list of
+ *   toplevel widgets
+ */
 GList*
 gtk_window_list_toplevels (void)
 {
@@ -2517,16 +2587,15 @@ gtk_window_unset_transient_for (GtkWindow *window)
 }
 
 /**
- * gtk_window_set_transient_for:
- * @window: a #GtkWindow
+ * gtk_window_set_transient_for: (attributes org.gtk.Method.set_property=transient-for)
+ * @window: a `GtkWindow`
  * @parent: (allow-none): parent window, or %NULL
  *
  * Dialog windows should be set transient for the main application
- * window they were spawned from. This allows
- * [window managers][gtk-X11-arch] to e.g. keep the
- * dialog on top of the main window, or center the dialog over the
- * main window. gtk_dialog_new_with_buttons() and other convenience
- * functions in GTK will sometimes call
+ * window they were spawned from. This allows window managers to e.g.
+ * keep the dialog on top of the main window, or center the dialog
+ * over the main window. [ctor@Gtk.Dialog.new_with_buttons] and other
+ * convenience functions in GTK will sometimes call
  * gtk_window_set_transient_for() on your behalf.
  *
  * Passing %NULL for @parent unsets the current transient window.
@@ -2588,15 +2657,14 @@ gtk_window_set_transient_for (GtkWindow *window,
 }
 
 /**
- * gtk_window_get_transient_for:
- * @window: a #GtkWindow
+ * gtk_window_get_transient_for: (attributes org.gtk.Method.get_property=transient-for)
+ * @window: a `GtkWindow`
  *
- * Fetches the transient parent for this window. See
- * gtk_window_set_transient_for().
+ * Fetches the transient parent for this window.
  *
  * Returns: (nullable) (transfer none): the transient parent for this
- * window, or %NULL if no transient parent has been set.
- **/
+ *   window, or %NULL if no transient parent has been set.
+ */
 GtkWindow *
 gtk_window_get_transient_for (GtkWindow *window)
 {
@@ -2608,13 +2676,13 @@ gtk_window_get_transient_for (GtkWindow *window)
 }
 
 /**
- * gtk_window_get_application:
- * @window: a #GtkWindow
+ * gtk_window_get_application: (attributes org.gtk.Method.get_property=application)
+ * @window: a `GtkWindow`
  *
- * Gets the #GtkApplication associated with the window (if any).
+ * Gets the `GtkApplication` associated with the window.
  *
- * Returns: (nullable) (transfer none): a #GtkApplication, or %NULL
- **/
+ * Returns: (nullable) (transfer none): a `GtkApplication`, or %NULL
+ */
 GtkApplication *
 gtk_window_get_application (GtkWindow *window)
 {
@@ -2647,23 +2715,24 @@ gtk_window_release_application (GtkWindow *window)
 }
 
 /**
- * gtk_window_set_application:
- * @window: a #GtkWindow
- * @application: (allow-none): a #GtkApplication, or %NULL to unset
+ * gtk_window_set_application: (attributes org.gtk.Method.set_property=application)
+ * @window: a `GtkWindow`
+ * @application: (allow-none): a `GtkApplication`, or %NULL to unset
  *
- * Sets or unsets the #GtkApplication associated with the window.
+ * Sets or unsets the `GtkApplication` associated with the window.
  *
- * The application will be kept alive for at least as long as it has any windows
- * associated with it (see g_application_hold() for a way to keep it alive
- * without windows).
+ * The application will be kept alive for at least as long as it has
+ * any windows associated with it (see g_application_hold() for a way
+ * to keep it alive without windows).
  *
- * Normally, the connection between the application and the window will remain
- * until the window is destroyed, but you can explicitly remove it by setting
- * the @application to %NULL.
+ * Normally, the connection between the application and the window will
+ * remain until the window is destroyed, but you can explicitly remove
+ * it by setting the @application to %NULL.
  *
- * This is equivalent to calling gtk_application_remove_window() and/or
- * gtk_application_add_window() on the old/new applications as relevant.
- **/
+ * This is equivalent to calling [method@Gtk.Application.remove_window]
+ * and/or [method@Gtk.Application.add_window] on the old/new applications
+ * as relevant.
+ */
 void
 gtk_window_set_application (GtkWindow      *window,
                             GtkApplication *application)
@@ -2703,15 +2772,16 @@ gtk_window_set_application (GtkWindow      *window,
 }
 
 /**
- * gtk_window_set_destroy_with_parent:
- * @window: a #GtkWindow
+ * gtk_window_set_destroy_with_parent: (attributes org.gtk.Method.set_property=destroy-with-parent)
+ * @window: a `GtkWindow`
  * @setting: whether to destroy @window with its transient parent
- * 
+ *
  * If @setting is %TRUE, then destroying the transient parent of @window
- * will also destroy @window itself. This is useful for dialogs that
- * shouldn’t persist beyond the lifetime of the main window they're
- * associated with, for example.
- **/
+ * will also destroy @window itself.
+ *
+ * This is useful for dialogs that shouldn’t persist beyond the lifetime
+ * of the main window they are associated with, for example.
+ */
 void
 gtk_window_set_destroy_with_parent (GtkWindow *window,
                                     gboolean   setting)
@@ -2729,14 +2799,13 @@ gtk_window_set_destroy_with_parent (GtkWindow *window,
 }
 
 /**
- * gtk_window_get_destroy_with_parent:
- * @window: a #GtkWindow
- * 
- * Returns whether the window will be destroyed with its transient parent. See
- * gtk_window_set_destroy_with_parent ().
+ * gtk_window_get_destroy_with_parent: (attributes org.gtk.Method.get_property=destroy-with-parent)
+ * @window: a `GtkWindow`
+ *
+ * Returns whether the window will be destroyed with its transient parent.
  *
  * Returns: %TRUE if the window will be destroyed with its transient parent.
- **/
+ */
 gboolean
 gtk_window_get_destroy_with_parent (GtkWindow *window)
 {
@@ -2748,8 +2817,8 @@ gtk_window_get_destroy_with_parent (GtkWindow *window)
 }
 
 /**
- * gtk_window_set_hide_on_close:
- * @window: a #GtkWindow
+ * gtk_window_set_hide_on_close: (attributes org.gtk.Method.set_property=hide-on-close)
+ * @window: a `GtkWindow`
  * @setting: whether to hide the window when it is closed
  *
  * If @setting is %TRUE, then clicking the close button on the window
@@ -2772,8 +2841,8 @@ gtk_window_set_hide_on_close (GtkWindow *window,
 }
 
 /**
- * gtk_window_get_hide_on_close:
- * @window: a #GtkWindow
+ * gtk_window_get_hide_on_close: (attributes org.gtk.Method.get_property=hide-on-close)
+ * @window: a `GtkWindow`
  *
  * Returns whether the window will be hidden when the close button is clicked.
  *
@@ -2867,19 +2936,20 @@ gtk_window_enable_csd (GtkWindow *window)
 
 /**
  * gtk_window_set_titlebar:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
  * @titlebar: (allow-none): the widget to use as titlebar
  *
  * Sets a custom titlebar for @window.
  *
- * A typical widget used here is #GtkHeaderBar, as it provides various features
- * expected of a titlebar while allowing the addition of child widgets to it.
+ * A typical widget used here is [class@Gtk.HeaderBar], as it
+ * provides various features expected of a titlebar while allowing
+ * the addition of child widgets to it.
  *
  * If you set a custom titlebar, GTK will do its best to convince
  * the window manager not to put its own titlebar on the window.
  * Depending on the system, this function may not work for a window
  * that is already visible, so you set the titlebar before calling
- * gtk_widget_show().
+ * [method@Gtk.Widget.show].
  */
 void
 gtk_window_set_titlebar (GtkWindow *window,
@@ -2928,7 +2998,7 @@ out:
 
 /**
  * gtk_window_get_titlebar:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
  *
  * Returns the custom titlebar that has been set with
  * gtk_window_set_titlebar().
@@ -2950,23 +3020,24 @@ gtk_window_get_titlebar (GtkWindow *window)
 }
 
 /**
- * gtk_window_set_decorated:
- * @window: a #GtkWindow
+ * gtk_window_set_decorated: (attributes org.gtk.Method.set_property=decorated)
+ * @window: a `GtkWindow`
  * @setting: %TRUE to decorate the window
  *
+ * Sets whether the window should be decorated.
+ *
  * By default, windows are decorated with a title bar, resize
- * controls, etc.  Some [window managers][gtk-X11-arch]
- * allow GTK to disable these decorations, creating a
- * borderless window. If you set the decorated property to %FALSE
- * using this function, GTK will do its best to convince the window
- * manager not to decorate the window. Depending on the system, this
- * function may not have any effect when called on a window that is
- * already visible, so you should call it before calling gtk_widget_show().
+ * controls, etc. Some window managers allow GTK to disable these
+ * decorations, creating a borderless window. If you set the decorated
+ * property to %FALSE using this function, GTK will do its best to
+ * convince the window manager not to decorate the window. Depending on
+ * the system, this function may not have any effect when called on a
+ * window that is already visible, so you should call it before calling
+ * [method@Gtk.Widget.show].
  *
  * On Windows, this function always works, since there’s no window manager
  * policy involved.
- * 
- **/
+ */
 void
 gtk_window_set_decorated (GtkWindow *window,
                           gboolean   setting)
@@ -2992,14 +3063,13 @@ gtk_window_set_decorated (GtkWindow *window,
 }
 
 /**
- * gtk_window_get_decorated:
- * @window: a #GtkWindow
+ * gtk_window_get_decorated: (attributes org.gtk.Method.get_property=decorated)
+ * @window: a `GtkWindow`
  *
- * Returns whether the window has been set to have decorations
- * such as a title bar via gtk_window_set_decorated().
+ * Returns whether the window has been set to have decorations.
  *
  * Returns: %TRUE if the window has been set to have decorations
- **/
+ */
 gboolean
 gtk_window_get_decorated (GtkWindow *window)
 {
@@ -3011,20 +3081,22 @@ gtk_window_get_decorated (GtkWindow *window)
 }
 
 /**
- * gtk_window_set_deletable:
- * @window: a #GtkWindow
+ * gtk_window_set_deletable: (attributes org.gtk.Method.set_property=deletable)
+ * @window: a `GtkWindow`
  * @setting: %TRUE to decorate the window as deletable
  *
- * By default, windows have a close button in the window frame. Some 
- * [window managers][gtk-X11-arch] allow GTK to 
- * disable this button. If you set the deletable property to %FALSE
- * using this function, GTK will do its best to convince the window
- * manager not to show a close button. Depending on the system, this
- * function may not have any effect when called on a window that is
- * already visible, so you should call it before calling gtk_widget_show().
+ * Sets whether the window should be deletable.
  *
- * On Windows, this function always works, since there’s no window manager
- * policy involved.
+ * By default, windows have a close button in the window frame.
+ * Some  window managers allow GTK to disable this button. If you
+ * set the deletable property to %FALSE using this function, GTK
+ * will do its best to convince the window manager not to show a
+ * close button. Depending on the system, this function may not
+ * have any effect when called on a window that is already visible,
+ * so you should call it before calling [method@Gtk.Widget.show].
+ *
+ * On Windows, this function always works, since there’s no window
+ * manager policy involved.
  */
 void
 gtk_window_set_deletable (GtkWindow *window,
@@ -3050,14 +3122,13 @@ gtk_window_set_deletable (GtkWindow *window,
 }
 
 /**
- * gtk_window_get_deletable:
- * @window: a #GtkWindow
+ * gtk_window_get_deletable: (attributes org.gtk.Method.get_property=deletable)
+ * @window: a `GtkWindow`
  *
- * Returns whether the window has been set to have a close button
- * via gtk_window_set_deletable().
+ * Returns whether the window has been set to have a close button.
  *
  * Returns: %TRUE if the window has been set to have a close button
- **/
+ */
 gboolean
 gtk_window_get_deletable (GtkWindow *window)
 {
@@ -3285,19 +3356,20 @@ update_themed_icon (GtkWindow *window)
 }
 
 /**
- * gtk_window_set_icon_name:
- * @window: a #GtkWindow
+ * gtk_window_set_icon_name: (attributes org.gtk.Method.set_property=icon-name)
+ * @window: a `GtkWindow`
  * @name: (allow-none): the name of the themed icon
  *
  * Sets the icon for the window from a named themed icon.
- * See the docs for #GtkIconTheme for more details.
+ *
+ * See the docs for [class@Gtk.IconTheme] for more details.
  * On some platforms, the window icon is not used at all.
  *
- * Note that this has nothing to do with the WM_ICON_NAME 
+ * Note that this has nothing to do with the WM_ICON_NAME
  * property which is mentioned in the ICCCM.
  */
-void 
-gtk_window_set_icon_name (GtkWindow   *window,
+void
+gtk_window_set_icon_name (GtkWindow  *window,
 			  const char *name)
 {
   GtkWindowIconInfo *info;
@@ -3320,11 +3392,10 @@ gtk_window_set_icon_name (GtkWindow   *window,
 }
 
 /**
- * gtk_window_get_icon_name:
- * @window: a #GtkWindow
+ * gtk_window_get_icon_name: (attributes org.gtk.Method.get_property=icon-name)
+ * @window: a `GtkWindow`
  *
- * Returns the name of the themed icon for the window,
- * see gtk_window_set_icon_name().
+ * Returns the name of the themed icon for the window.
  *
  * Returns: (nullable): the icon name or %NULL if the window has
  * no themed icon
@@ -3345,9 +3416,12 @@ gtk_window_get_icon_name (GtkWindow *window)
  * gtk_window_set_default_icon_name:
  * @name: the name of the themed icon
  *
- * Sets an icon to be used as fallback for windows that
- * haven't had gtk_window_set_icon_name() called on them.
- **/
+ * Sets an icon to be used as fallback.
+ *
+ * The fallback icon is used for windows that
+ * haven't had [method@Gtk.Window.set_icon_name]
+ * called on them.
+ */
 void
 gtk_window_set_default_icon_name (const char *name)
 {
@@ -3381,12 +3455,11 @@ gtk_window_set_default_icon_name (const char *name)
 /**
  * gtk_window_get_default_icon_name:
  *
- * Returns the fallback icon name for windows that has been set
- * with gtk_window_set_default_icon_name(), or %NULL if that function
- * has not been called.
+ * Returns the fallback icon name for windows.
  *
- * The returned string is owned by GTK and should not be modified.
- * It is only valid until the next call to gtk_window_set_default_icon_name().
+ * The returned string is owned by GTK and should not
+ * be modified. It is only valid until the next call to
+ * [func@Gtk.Window.set_default_icon_name].
  *
  * Returns: (nullable): the fallback icon name for windows
  */
@@ -3464,20 +3537,22 @@ gtk_window_set_default_size_internal (GtkWindow    *window,
 
 /**
  * gtk_window_set_default_size:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
  * @width: width in pixels, or -1 to unset the default width
  * @height: height in pixels, or -1 to unset the default height
  *
- * Sets the default size of a window. If the window’s “natural” size
- * (its size request) is larger than the default, the default will be
- * ignored.
+ * Sets the default size of a window.
+ *
+ * If the window’s “natural” size (its size request) is larger than
+ * the default, the default will be ignored.
  *
- * Unlike gtk_widget_set_size_request(), which sets a size request for
- * a widget and thus would keep users from shrinking the window, this
- * function only sets the initial size, just as if the user had
- * resized the window themselves. Users can still shrink the window
- * again as they normally would. Setting a default size of -1 means to
- * use the “natural” default size (the size request of the window).
+ * Unlike [method@Gtk.Widget.set_size_request], which sets a size
+ * request for a widget and thus would keep users from shrinking
+ * the window, this function only sets the initial size, just as
+ * if the user had resized the window themselves. Users can still
+ * shrink the window again as they normally would. Setting a default
+ * size of -1 means to use the “natural” default size (the size request
+ * of the window).
  *
  * The default size of a window only affects the first time a window is
  * shown; if a window is hidden and re-shown, it will remember the size
@@ -3488,8 +3563,9 @@ gtk_window_set_default_size_internal (GtkWindow    *window,
  *
  * If you use this function to reestablish a previously saved window size,
  * note that the appropriate size to save is the one returned by
- * gtk_window_get_default_size(). Using the window allocation directly will not
- * work in all circumstances and can lead to growing or shrinking windows.
+ * [method@Gtk.Window.get_default_size]. Using the window allocation
+ * directly will not work in all circumstances and can lead to growing
+ * or shrinking windows.
  */
 void
 gtk_window_set_default_size (GtkWindow   *window,
@@ -3506,15 +3582,16 @@ gtk_window_set_default_size (GtkWindow   *window,
 
 /**
  * gtk_window_get_default_size:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
  * @width: (out) (allow-none): location to store the default width, or %NULL
  * @height: (out) (allow-none): location to store the default height, or %NULL
  *
- * Gets the default size of the window. A value of 0 for the width or
- * height indicates that a default size has not been explicitly set
- * for that dimension, so the “natural” size of the window will be
- * used.
- **/
+ * Gets the default size of the window.
+ *
+ * A value of 0 for the width or height indicates that a default
+ * size has not been explicitly set for that dimension, so the
+ * “natural” size of the window will be used.
+ */
 void
 gtk_window_get_default_size (GtkWindow *window,
 			     int       *width,
@@ -4960,17 +5037,19 @@ synthesize_focus_change_events (GtkWindow       *window,
 }
 
 /**
- * gtk_window_set_focus:
- * @window: a #GtkWindow
+ * gtk_window_set_focus: (attributes org.gtk.Method.set_property=focus-widget)
+ * @window: a `GtkWindow`
  * @focus: (allow-none): widget to be the new focus widget, or %NULL to unset
  *   any focus widget for the toplevel window.
  *
- * If @focus is not the current focus widget, and is focusable, sets
- * it as the focus widget for the window. If @focus is %NULL, unsets
- * the focus widget for this window. To set the focus to a particular
- * widget in the toplevel, it is usually more convenient to use
- * gtk_widget_grab_focus() instead of this function.
- **/
+ * Sets the focus widget.
+ *
+ * If @focus is not the current focus widget, and is focusable,
+ * sets it as the focus widget for the window. If @focus is %NULL,
+ * unsets the focus widget for this window. To set the focus to a
+ * particular widget in the toplevel, it is usually more convenient
+ * to use [method@Gtk.Widget.grab_focus] instead of this function.
+ */
 void
 gtk_window_set_focus (GtkWindow *window,
                       GtkWidget *focus)
@@ -5032,12 +5111,14 @@ _gtk_window_unset_focus_and_default (GtkWindow *window,
 
 /**
  * gtk_window_present:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
  *
- * Presents a window to the user. This function should not be used
- * as when it is called, it is too late to gather a valid timestamp
- * to allow focus stealing prevention to work correctly.
- **/
+ * Presents a window to the user.
+ *
+ * This function should not be used as when it is called,
+ * it is too late to gather a valid timestamp to allow focus
+ * stealing prevention to work correctly.
+ */
 void
 gtk_window_present (GtkWindow *window)
 {
@@ -5046,29 +5127,31 @@ gtk_window_present (GtkWindow *window)
 
 /**
  * gtk_window_present_with_time:
- * @window: a #GtkWindow
- * @timestamp: the timestamp of the user interaction (typically a 
+ * @window: a `GtkWindow`
+ * @timestamp: the timestamp of the user interaction (typically a
  *   button or key press event) which triggered this call
  *
- * Presents a window to the user. This may mean raising the window
- * in the stacking order, unminimizing it, moving it to the current
- * desktop, and/or giving it the keyboard focus, possibly dependent
- * on the user’s platform, window manager, and preferences.
+ * Presents a window to the user.
  *
- * If @window is hidden, this function calls gtk_widget_show()
+ * This may mean raising the window in the stacking order,
+ * unminimizing it, moving it to the current desktop, and/or
+ * giving it the keyboard focus, possibly dependent on the user’s
+ * platform, window manager, and preferences.
+ *
+ * If @window is hidden, this function calls [method@Gtk.Widget.show]
  * as well.
  *
  * This function should be used when the user tries to open a window
  * that’s already open. Say for example the preferences dialog is
  * currently open, and the user chooses Preferences from the menu
- * a second time; use gtk_window_present() to move the already-open dialog
- * where the user can see it.
+ * a second time; use [method@Gtk.Window.present] to move the
+ * already-open dialog where the user can see it.
  *
- * Presents a window to the user in response to a user interaction. The
- * timestamp should be gathered when the window was requested to be shown
- * (when clicking a link for example), rather than once the window is
- * ready to be shown.
- **/
+ * Presents a window to the user in response to a user interaction.
+ * The timestamp should be gathered when the window was requested
+ * to be shown (when clicking a link for example), rather than once
+ * the window is ready to be shown.
+ */
 void
 gtk_window_present_with_time (GtkWindow *window,
 			      guint32    timestamp)
@@ -5114,13 +5197,13 @@ gtk_window_present_with_time (GtkWindow *window,
 
 /**
  * gtk_window_minimize:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
  *
  * Asks to minimize the specified @window.
  *
  * Note that you shouldn’t assume the window is definitely minimized
  * afterward, because the windowing system might not support this
- * functionality; other entities (e.g. the user or the [window manager][gtk-X11-arch])
+ * functionality; other entities (e.g. the user or the window manager
  * could unminimize it again, or there may not be a window manager in
  * which case minimization isn’t possible, etc.
  *
@@ -5128,8 +5211,8 @@ gtk_window_present_with_time (GtkWindow *window,
  * in which case the window will be minimized before it ever appears
  * onscreen.
  *
- * You can track result of this operation via the #GdkToplevel:state
- * property.
+ * You can track result of this operation via the
+ * [property@Gdk.Toplevel:state] property.
  */
 void
 gtk_window_minimize (GtkWindow *window)
@@ -5146,18 +5229,18 @@ gtk_window_minimize (GtkWindow *window)
 
 /**
  * gtk_window_unminimize:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
  *
  * Asks to unminimize the specified @window.
  *
  * Note that you shouldn’t assume the window is definitely unminimized
  * afterward, because the windowing system might not support this
- * functionality; other entities (e.g. the user or the [window manager][gtk-X11-arch])
+ * functionality; other entities (e.g. the user or the window manager
  * could minimize it again, or there may not be a window manager in
  * which case minimization isn’t possible, etc.
  *
- * You can track result of this operation via the #GdkToplevel:state
- * property.
+ * You can track result of this operation via the
+ * [property@Gdk.Toplevel:state] property.
  */
 void
 gtk_window_unminimize (GtkWindow *window)
@@ -5174,19 +5257,22 @@ gtk_window_unminimize (GtkWindow *window)
 
 /**
  * gtk_window_maximize:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
  *
  * Asks to maximize @window, so that it fills the screen.
  *
- * Note that you shouldn’t assume the window is definitely maximized afterward,
- * because other entities (e.g. the user or [window manager][gtk-X11-arch])
- * could unmaximize it again, and not all window managers support maximization.
+ * Note that you shouldn’t assume the window is definitely maximized
+ * afterward, because other entities (e.g. the user or window manager
+ * could unmaximize it again, and not all window managers support
+ * maximization.
  *
- * It’s permitted to call this function before showing a window, in which case
- * the window will be maximized when it appears onscreen initially.
+ * It’s permitted to call this function before showing a window,
+ * in which case the window will be maximized when it appears onscreen
+ * initially.
  *
- * You can track the result of this operation via the #GdkToplevel:state
- * property, or by listening to notifications on the #GtkWindow:maximized
+ * You can track the result of this operation via the
+ * [property@Gdk.Toplevel:state] property, or by listening to
+ * notifications on the [property@Gtk.Window:maximized]
  * property.
  */
 void
@@ -5213,17 +5299,18 @@ gtk_window_maximize (GtkWindow *window)
 
 /**
  * gtk_window_unmaximize:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
  *
  * Asks to unmaximize @window.
  *
- * Note that you shouldn’t assume the window is definitely unmaximized afterward,
- * because other entities (e.g. the user or [window manager][gtk-X11-arch]) could
- * maximize it again, and not all window managers honor requests to unmaximize.
+ * Note that you shouldn’t assume the window is definitely unmaximized
+ * afterward, because other entities (e.g. the user or window manager
+ * maximize it again, and not all window managers honor requests to
+ * unmaximize.
  *
- * You can track the result of this operation via the #GdkToplevel:state
- * property, or by listening to notifications on the #GtkWindow:maximized
- * property.
+ * You can track the result of this operation via the
+ * [property@Gdk.Toplevel:state] property, or by listening to
+ * notifications on the [property@Gtk.Window:maximized] property.
  */
 void
 gtk_window_unmaximize (GtkWindow *window)
@@ -5262,17 +5349,18 @@ unset_fullscreen_monitor (GtkWindow *window)
 
 /**
  * gtk_window_fullscreen:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
  *
  * Asks to place @window in the fullscreen state.
  *
- * Note that you shouldn’t assume the window is definitely full screen afterward,
- * because other entities (e.g. the user or [window manager][gtk-X11-arch]) could
- * unfullscreen it again, and not all window managers honor requests to fullscreen
- * windows.
+ * Note that you shouldn’t assume the window is definitely fullscreen
+ * afterward, because other entities (e.g. the user or window manager
+ * unfullscreen it again, and not all window managers honor requests
+ * to fullscreen windows.
  *
- * You can track the result of this operation via the #GdkToplevel:state property,
- * or by listening to notifications of the #GtkWindow:fullscreened property.
+ * You can track the result of this operation via the
+ * [property@Gdk.Toplevel:state] property, or by listening to
+ * notifications of the [property@Gtk.Window:fullscreened] property.
  */
 void
 gtk_window_fullscreen (GtkWindow *window)
@@ -5300,18 +5388,18 @@ gtk_window_fullscreen (GtkWindow *window)
 
 /**
  * gtk_window_fullscreen_on_monitor:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
  * @monitor: which monitor to go fullscreen on
  *
  * Asks to place @window in the fullscreen state on the given @monitor.
  *
- * Note that you shouldn't assume the window is definitely full screen
+ * Note that you shouldn't assume the window is definitely fullscreen
  * afterward, or that the windowing system allows fullscreen windows on
  * any given monitor.
  *
- * You can track the result of this operation via the #GdkToplevel:state
- * property, or by listening to notifications of the #GtkWindow:fullscreened
- * property.
+ * You can track the result of this operation via the
+ * [property@Gdk.Toplevel:state] property, or by listening to
+ * notifications of the [property@Gtk.Window:fullscreened] property.
  */
 void
 gtk_window_fullscreen_on_monitor (GtkWindow  *window,
@@ -5348,19 +5436,21 @@ gtk_window_fullscreen_on_monitor (GtkWindow  *window,
 
 /**
  * gtk_window_unfullscreen:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
  *
- * Asks to remove the fullscreen state for @window, and return to its previous
- * state.
+ * Asks to remove the fullscreen state for @window, and return to
+ * its previous state.
  *
- * Note that you shouldn’t assume the window is definitely not full screen afterward,
- * because other entities (e.g. the user or [window manager][gtk-X11-arch]) could
- * fullscreen it again, and not all window managers honor requests to unfullscreen
- * windows; normally the window will end up restored to its normal state. Just don’t
+ * Note that you shouldn’t assume the window is definitely not
+ * fullscreen afterward, because other entities (e.g. the user or
+ * window manager could fullscreen it again, and not all window
+ * managers honor requests to unfullscreen windows; normally the
+ * window will end up restored to its normal state. Just don’t
  * write code that crashes if not.
  *
- * You can track the result of this operation via the #GdkToplevel:state property,
- * or by listening to notifications of the #GtkWindow:fullscreened property.
+ * You can track the result of this operation via the
+ * [property@Gdk.Toplevel:state] property, or by listening to
+ * notifications of the [property@Gtk.Window:fullscreened] property.
  */
 void
 gtk_window_unfullscreen (GtkWindow *window)
@@ -5387,8 +5477,8 @@ gtk_window_unfullscreen (GtkWindow *window)
 }
 
 /**
- * gtk_window_set_resizable:
- * @window: a #GtkWindow
+ * gtk_window_set_resizable: (attributes org.gtk.Method.set_property=resizable)
+ * @window: a `GtkWindow`
  * @resizable: %TRUE if the user can resize this window
  *
  * Sets whether the user can resize a window.
@@ -5418,8 +5508,8 @@ gtk_window_set_resizable (GtkWindow *window,
 }
 
 /**
- * gtk_window_get_resizable:
- * @window: a #GtkWindow
+ * gtk_window_get_resizable: (attributes org.gtk.Method.get_property=resizable)
+ * @window: a `GtkWindow`
  *
  * Gets the value set by gtk_window_set_resizable().
  *
@@ -5436,13 +5526,14 @@ gtk_window_get_resizable (GtkWindow *window)
 }
 
 /**
- * gtk_window_set_display:
- * @window: a #GtkWindow.
- * @display: a #GdkDisplay.
+ * gtk_window_set_display: (attributes org.gtk.Method.set_property=display)
+ * @window: a `GtkWindow`
+ * @display: a `GdkDisplay`
+ *
+ * Sets the `GdkDisplay` where the @window is displayed.
  *
- * Sets the #GdkDisplay where the @window is displayed; if
- * the window is already mapped, it will be unmapped, and
- * then remapped on the new display.
+ * If the window is already mapped, it will be unmapped,
+ * and then remapped on the new display.
  */
 void
 gtk_window_set_display (GtkWindow  *window,
@@ -5524,17 +5615,19 @@ gtk_window_on_theme_variant_changed (GtkSettings *settings,
 #endif
 
 /**
- * gtk_window_is_active:
- * @window: a #GtkWindow
- * 
+ * gtk_window_is_active: (attributes org.gtk.Method.get_property=is-active)
+ * @window: a `GtkWindow`
+ *
  * Returns whether the window is part of the current active toplevel.
- * (That is, the toplevel window receiving keystrokes.)
+ *
+ * The active toplevel is the window receiving keystrokes.
+ *
  * The return value is %TRUE if the window is active toplevel itself.
  * You might use this function if you wanted to draw a widget
  * differently in an active window from a widget in an inactive window.
- * 
+ *
  * Returns: %TRUE if the window part of the current active window.
- **/
+ */
 gboolean
 gtk_window_is_active (GtkWindow *window)
 {
@@ -5547,13 +5640,14 @@ gtk_window_is_active (GtkWindow *window)
 
 /**
  * gtk_window_get_group:
- * @window: (allow-none): a #GtkWindow, or %NULL
+ * @window: (allow-none): a `GtkWindow`, or %NULL
+ *
+ * Returns the group for @window.
  *
- * Returns the group for @window or the default group, if
- * @window is %NULL or if @window does not have an explicit
- * window group.
+ * If the window has no group, then the default group is returned.
  *
- * Returns: (transfer none): the #GtkWindowGroup for a window or the default group
+ * Returns: (transfer none): the `GtkWindowGroup` for a window
+ *   or the default group
  */
 GtkWindowGroup *
 gtk_window_get_group (GtkWindow *window)
@@ -5575,12 +5669,12 @@ gtk_window_get_group (GtkWindow *window)
 
 /**
  * gtk_window_has_group:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
  *
  * Returns whether @window has an explicit window group.
  *
  * Returns: %TRUE if @window has an explicit window group.
- **/
+ */
 gboolean
 gtk_window_has_group (GtkWindow *window)
 {
@@ -5654,13 +5748,13 @@ gtk_window_keys_changed (GtkWindow *window)
 
 /*
  * _gtk_window_set_is_active:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
  * @is_active: %TRUE if the window is in the currently active toplevel
  *
- * Internal function that sets whether the #GtkWindow is part
- * of the currently active toplevel window (taking into account inter-process
- * embedding.)
- **/
+ * Internal function that sets whether the `GtkWindow` is part
+ * of the currently active toplevel window (taking into account
+ * inter-process embedding.)
+ */
 static void
 _gtk_window_set_is_active (GtkWindow *window,
                            gboolean   is_active)
@@ -5693,9 +5787,11 @@ _gtk_window_set_is_active (GtkWindow *window,
  * gtk_window_set_auto_startup_notification:
  * @setting: %TRUE to automatically do startup notification
  *
- * By default, after showing the first #GtkWindow, GTK calls
- * gdk_display_notify_startup_complete(). Call this function to
- * disable the automatic startup notification. You might do this
+ * Sets whether the window should request startup notification.
+ *
+ * By default, after showing the first `GtkWindow`, GTK calls
+ * [method@Gdk.Display.notify_startup_complete]. Call this function
+ * to disable the automatic startup notification. You might do this
  * if your first window is a splash screen, and you want to delay
  * notification until after your real main window has been shown,
  * for example.
@@ -5703,7 +5799,7 @@ _gtk_window_set_is_active (GtkWindow *window,
  * In that example, you would disable startup notification
  * temporarily, show your splash screen, then re-enable it so that
  * showing the main window would automatically result in notification.
- **/
+ */
 void
 gtk_window_set_auto_startup_notification (gboolean setting)
 {
@@ -5711,13 +5807,13 @@ gtk_window_set_auto_startup_notification (gboolean setting)
 }
 
 /**
- * gtk_window_get_mnemonics_visible:
- * @window: a #GtkWindow
+ * gtk_window_get_mnemonics_visible: (attributes org.gtk.MEthod.get_property=mnemonics-visible)
+ * @window: a `GtkWindow`
  *
- * Gets the value of the #GtkWindow:mnemonics-visible property.
+ * Gets whether mnemonics are supposed to be visible.
  *
  * Returns: %TRUE if mnemonics are supposed to be visible
- * in this window.
+ *   in this window.
  */
 gboolean
 gtk_window_get_mnemonics_visible (GtkWindow *window)
@@ -5731,10 +5827,10 @@ gtk_window_get_mnemonics_visible (GtkWindow *window)
 
 /**
  * gtk_window_set_mnemonics_visible:
- * @window: a #GtkWindow
+ * @window: a `GtkWindow`
  * @setting: the new value
  *
- * Sets the #GtkWindow:mnemonics-visible property.
+ * Sets whether mnemonics are supposed to be visible.
  */
 void
 gtk_window_set_mnemonics_visible (GtkWindow *window,
@@ -5788,13 +5884,13 @@ _gtk_window_schedule_mnemonics_visible (GtkWindow *window)
 }
 
 /**
- * gtk_window_get_focus_visible:
- * @window: a #GtkWindow
+ * gtk_window_get_focus_visible: (attributes org.gtk.Method.get_property=focus-visible)
+ * @window: a `GtkWindow`
  *
- * Gets the value of the #GtkWindow:focus-visible property.
+ * Gets whether “focus rectangles” are supposed to be visible.
  *
  * Returns: %TRUE if “focus rectangles” are supposed to be visible
- *     in this window.
+ *   in this window.
  */
 gboolean
 gtk_window_get_focus_visible (GtkWindow *window)
@@ -5820,11 +5916,11 @@ unset_focus_visible (gpointer data)
 }
 
 /**
- * gtk_window_set_focus_visible:
- * @window: a #GtkWindow
+ * gtk_window_set_focus_visible: (attributes org.gtk.MEthod.set_property=focus-visible)
+ * @window: a `GtkWindow`
  * @setting: the new value
  *
- * Sets the #GtkWindow:focus-visible property.
+ * Sets whether “focus rectangles” are supposed to be visible.
  */
 void
 gtk_window_set_focus_visible (GtkWindow *window,
@@ -5979,8 +6075,9 @@ gtk_window_set_debugging (GdkDisplay *display,
  * gtk_window_set_interactive_debugging:
  * @enable: %TRUE to enable interactive debugging
  *
- * Opens or closes the [interactive debugger][interactive-debugging],
- * which offers access to the widget hierarchy of the application
+ * Opens or closes the [interactive debugger](#interactive-debugging).
+ *
+ * The debugger offers access to the widget hierarchy of the application
  * and to useful debugging tools.
  */
 void
@@ -6418,8 +6515,8 @@ gtk_window_maybe_update_cursor (GtkWindow *window,
 }
 
 /**
- * gtk_window_set_child:
- * @window: a #GtkWindow
+ * gtk_window_set_child: (attributes org.gtk.Method.set_property=child)
+ * @window: a `GtkWindow`
  * @child: (allow-none): the child widget
  *
  * Sets the child widget of @window.
@@ -6445,8 +6542,8 @@ gtk_window_set_child (GtkWindow *window,
 }
 
 /**
- * gtk_window_get_child:
- * @window: a #GtkWindow
+ * gtk_window_get_child: (attributes org.gtk.Method.get_property=child)
+ * @window: a `GtkWindow`
  *
  * Gets the child widget of @window.
  *
-- 
2.30.2